<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Feed_Pubsubhubbub - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.feed.pubsubhubbub.introduction.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.feed.pubsubhubbub.introduction.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.feed.writer.html">Zend_Feed_Writer</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.feed.html">Zend_Feed</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.file.html">Zend_File</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.feed.pubsubhubbub.introduction" class="section"><div class="info"><h1 class="title">Zend_Feed_Pubsubhubbub</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Feed_Pubsubhubbub</span> is an implementation of the PubSubHubbub Core
        0.2 Specification (Working Draft). It offers implementations of a Pubsubhubbub Publisher and
        Subscriber suited to Zend Framework and other <acronym class="acronym">PHP</acronym> applications.
    </p>

    <div class="section" id="zend.feed.pubsubhubbub.what.is.pubsubhubbub"><div class="info"><h1 class="title">What is Pubsubhubbub?</h1></div>
        

        <p class="para">
            Pubsubhubbub is an open, simple web-scale pubsub protocol. A common use case to enable
            blogs (Publishers) to &quot;push&quot; updates from their <acronym class="acronym">RSS</acronym> or Atom feeds
            (Topics) to end Subscribers. These Subscribers will have subscribed to the blog&#039;s
            <acronym class="acronym">RSS</acronym> or Atom feed via a Hub, a central server which is notified of any
            updates by the Publisher and which then distributes these updates to all Subscribers.
            Any feed may advertise that it supports one or more Hubs using an Atom namespaced link
            element with a rel attribute of &quot;hub&quot;.
        </p>

        <p class="para">
            Pubsubhubbub has garnered attention because it is a pubsub protocol which is easy to
            implement and which operates over <acronym class="acronym">HTTP</acronym>. Its philosophy is to replace
            the traditional model where blog feeds have been polled at regular intervals to detect
            and retrieve updates. Depending on the frequency of polling, this can take a lot of time
            to propagate updates to interested parties from planet aggregators to desktop readers.
            With a pubsub system in place, updates are not simply polled by Subscribers, they are
            pushed to Subscribers, elimenating any delay. For this reason, Pubsubhubbub forms part
            of what has been dubbed the real-time web.
        </p>

        <p class="para">
            The protocol does not exist in isolation. Pubsub systems have been around for a while,
            such as the familiar Jabber Publish-Subscribe protocol, <acronym class="acronym">XEP-0060</acronym>, or
            the less well known rssCloud (described in 2001). However these have not achieved
            widespread adoption typically due to either their complexity, poor timing or lack of
            suitability for web applications. rssCloud, which was recently revived as a response to
            the appearance of Pubsubhubbub, has also seen its usage increase significantly though it
            lacks a formal specification and currently does not support Atom 1.0 feeds.
        </p>

        <p class="para">
            Perhaps surprisingly given its relative early age, Pubsubhubbub is already in use
            including in Google Reader, Feedburner, and there are plugins available for Wordpress
            blogs.
        </p>
    </div>

    <div class="section" id="zend.feed.pubsubhubbub.architecture"><div class="info"><h1 class="title">Architecture</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Feed_Pubsubhubbub</span> implements two sides of the Pubsubhubbub
            0.2 Specification: a Publisher and a Subscriber. It does not currently implement a Hub
            Server though this is in progress for a future Zend Framework release.
        </p>

        <p class="para">
            A Publisher is responsible for notifying all supported Hubs (many can be supported to
            add redundancy to the system) of any updates to its feeds, whether they be Atom or
            <acronym class="acronym">RSS</acronym> based. This is achieved by pinging the supported Hub Servers with
            the <acronym class="acronym">URL</acronym> of the updated feed. In Pubsubhubbub terminology, any
            updatable resource capable of being subscribed to is referred to as a Topic. Once a ping
            is received, the Hub will request the updated feed, process it for updated items, and
            forward all updates to all Subscribers subscribed to that feed.
        </p>

        <p class="para">
            A Subscriber is any party or application which subscribes to one or more Hubs to receive
            updates from a Topic hosted by a Publisher. The Subscriber never directly communicates
            with the Publisher since the Hub acts as an intermediary, accepting subscriptions and
            sending updates to subscribed Subscribers. The Subscriber therefore communicates only
            with the Hub, either to subscribe or unsubscribe to Topics, or when it receives updates
            from the Hub. This communication design (&quot;Fat Pings&quot;) effectively removes the
            possibility of a &quot;Thundering Herd&quot; issue. This occurs in a pubsub system where the Hub
            merely informs Subscribers that an update is available, prompting all Subscribers to
            immediately retrieve the feed from the Publisher giving rise to a traffic spike. In
            Pubsubhubbub, the Hub distributes the actual update in a &quot;Fat Ping&quot; so the Publisher is
            not subjected to any traffic spike.
        </p>

        <p class="para">
            <span class="classname">Zend_Feed_Pubsubhubbub</span> implements Pubsubhubbub Publishers and
            Subscribers with the
            classes <span class="classname">Zend_Feed_Pubsubhubbub_Publisher</span> and
            <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber</span>. In addition, the Subscriber
            implementation may handle any feed updates forwarded from a Hub by using
            <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span>. These classes, their
            use cases, and <acronym class="acronym">API</acronym>s are covered in subsequent sections.
        </p>
    </div>

    <div class="section" id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.publisher"><div class="info"><h1 class="title">Zend_Feed_Pubsubhubbub_Publisher</h1></div>
        

        <p class="para">
            In Pubsubhubbub, the Publisher is the party who publishes a live feed and frequently
            updates it with new content. This may be a blog, an aggregator, or even a web service
            with a public feed based <acronym class="acronym">API</acronym>. In order for these updates to be pushed
            to Subscribers, the Publisher must notify all of its supported Hubs that an update has
            occured using a simple <acronym class="acronym">HTTP</acronym> <acronym class="acronym">POST</acronym> request
            containing the <acronym class="acronym">URI</acronym> or the updated Topic (i.e the updated
            <acronym class="acronym">RSS</acronym> or Atom feed). The Hub will confirm receipt of the notification,
            fetch the updated feed, and forward any updates to any Subscribers who have subscribed
            to that Hub for updates from the relevant feed.
        </p>

        <p class="para">
            By design, this means the Publisher has very little to do except send these Hub pings
            whenever its feeds change. As a result, the Publisher implementation is extremely
            simple to use and requires very little work to setup and use when feeds are updated.
        </p>

        <p class="para">
            <span class="classname">Zend_Feed_Pubsubhubbub_Publisher</span> implements a full Pubsubhubbub
            Publisher. Its setup for use is also simple, requiring mainly that it is configured with
            the <acronym class="acronym">URI</acronym> endpoint for all Hubs to be notified of updates, and the
            <acronym class="acronym">URI</acronym>s of all Topics to be included in the notifications.
        </p>

        <p class="para">
            The following example shows a Publisher notifying a collection of Hubs about updates to
            a pair of local <acronym class="acronym">RSS</acronym> and Atom feeds. The class retains a collection of
            errors which include the Hub <acronym class="acronym">URL</acronym>s, so the notification can be
            re-attempted later and/or logged if any notifications happen to fail. Each resulting
            error array also includes a &quot;response&quot; key containing the related
            <acronym class="acronym">HTTP</acronym> response object. In the event of any errors, it is strongly
            recommended to attempt the operation for failed Hub Endpoints at least once more at a
            future time. This may require the use of either a scheduled task for this purpose or a
            job queue though such extra steps are optional.
        </p>

        <pre class="programlisting brush: php">
$publisher = new Zend_Feed_Pubsubhubbub_Publisher;
$publisher-&gt;addHubUrls(array(
    &#039;http://pubsubhubbub.appspot.com/&#039;,
    &#039;http://hubbub.example.com&#039;,
));
$publisher-&gt;addUpdatedTopicUrls(array(
    &#039;http://www.example.net/rss&#039;,
    &#039;http://www.example.net/atom&#039;,
));
$publisher-&gt;notifyAll();

if (!$publisher-&gt;isSuccess()) {
    // check for errors
    $errors     = $publisher-&gt;getErrors();
    $failedHubs = array()
    foreach ($errors as $error) {
        $failedHubs[] = $error[&#039;hubUrl&#039;];
    }
}

// reschedule notifications for the failed Hubs in $failedHubs
</pre>


        <p class="para">
            If you prefer having more concrete control over the Publisher, the methods
             <span class="methodname">addHubUrls()</span> and  <span class="methodname">addUpdatedTopicUrls()</span>
            pass each array value to the singular  <span class="methodname">addHubUrl()</span> and
             <span class="methodname">addUpdatedTopicUrl()</span> public methods. There are also matching
             <span class="methodname">removeUpdatedTopicUrl()</span> and
             <span class="methodname">removeHubUrl()</span> methods.
        </p>

        <p class="para">
            You can also skip setting Hub <acronym class="acronym">URI</acronym>s, and notify each in turn using the
             <span class="methodname">notifyHub()</span> method which accepts the <acronym class="acronym">URI</acronym> of
            a Hub endpoint as its only argument.
        </p>

        <p class="para">
            There are no other tasks to cover. The Publisher implementation is very simple since
            most of the feed processing and distribution is handled by the selected Hubs. It is
            however important to detect errors and reschedule notifications as soon as possible
            (with a reasonable maximum number of retries) to ensure notifications reach all
            Subscribers. In many cases as a final alternative, Hubs may frequently poll your
            feeds to offer some additional tolerance for failures both in terms of their own
            temporary downtime or Publisher errors or downtime.
        </p>
    </div>

    <div class="section" id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.subscriber"><div class="info"><h1 class="title">Zend_Feed_Pubsubhubbub_Subscriber</h1></div>
        

        <p class="para">
            In Pubsubhubbub, the Subscriber is the party who wishes to receive updates to any Topic
            (<acronym class="acronym">RSS</acronym> or Atom feed). They achieve this by subscribing to one or more
            of the Hubs advertised by that Topic, usually as a set of one or more Atom 1.0 links
            with a rel attribute of &quot;hub&quot;. The Hub from that point forward will send an Atom or
            <acronym class="acronym">RSS</acronym> feed containing all updates to that Subscriber&#039;s Callback
            <acronym class="acronym">URL</acronym> when it receives an update notification from the Publisher. In
            this way, the Subscriber need never actually visit the original feed (though it&#039;s still
            recommended at some level to ensure updates are retrieved if ever a Hub goes offline).
            All subscription requests must contain the <acronym class="acronym">URI</acronym> of the Topic being
            subscribed and a Callback <acronym class="acronym">URL</acronym> which the Hub will use to confirm the
            subscription and to forward updates.
        </p>

        <p class="para">
            The Subsciber therefore has two roles. To create and manage subscriptions, including
            subscribing for new Topics with a Hub, unsubscribing (if necessary), and periodically
            renewing subscriptions since they may have a limited validity as set by the Hub. This is
            handled by <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber</span>.
        </p>

        <p class="para">
            The second role is to accept updates sent by a Hub to the Subscriber&#039;s Callback
            <acronym class="acronym">URL</acronym>, i.e. the <acronym class="acronym">URI</acronym> the Subscriber has assigned to
            handle updates. The Callback <acronym class="acronym">URL</acronym> also handles events where the Hub
            contacts the Subscriber to confirm all subscriptions and unsubscriptions. This is
            handled by using an instance of
            <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> when the Callback
            <acronym class="acronym">URL</acronym> is accessed.
        </p>

        <div class="important"><b class="important">Important</b>
            <p class="para">
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber</span> implements the Pubsubhubbub
                0.2 Specification. As this is a new specification version not all Hubs currently
                implement it. The new specification allows the Callback <acronym class="acronym">URL</acronym> to
                include a query string which is used by this class, but not supported by all Hubs.
                In the interests of maximising compatibility it is therefore recommended that the
                query string component of the Subscriber Callback <acronym class="acronym">URI</acronym> be
                presented as a path element, i.e. recognised as a parameter in the route associated
                with the Callback <acronym class="acronym">URI</acronym> and used by the application&#039;s Router.
            </p>
        </div>

        <div class="section" id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.subscriber.subscribing.and.unsubscribing"><div class="info"><h1 class="title">Subscribing and Unsubscribing</h1></div>
            

            <p class="para">
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber</span> implements a full
                Pubsubhubbub Subscriber capable of subscribing to, or unsubscribing from, any Topic
                via any Hub advertised by that Topic. It operates in conjunction with
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> which accepts
                requests from a Hub to confirm all subscription or unsubscription attempts (to
                prevent third-party misuse).
            </p>

            <p class="para">
                Any subscription (or unsubscription) requires the relevant information before
                proceeding, i.e. the <acronym class="acronym">URI</acronym> of the Topic (Atom or
                <acronym class="acronym">RSS</acronym> feed) to be subscribed to for updates, and the
                <acronym class="acronym">URI</acronym> of the endpoint for the Hub which will handle the
                subscription and forwarding of the updates. The lifetime of a subscription may
                be determined by the Hub but most Hubs should support automatic subscription
                refreshes by checking with the Subscriber. This is supported by
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> and requires no
                other work on your part. It is still strongly recommended that you use the Hub
                sourced subscription time to live (ttl) to schedule the creation of new
                subscriptions (the process is identical to that for any new subscription) to refresh
                it with the Hub. While it should not be necessary per se, it covers cases where a
                Hub may not support automatic subscription refreshing and rules out Hub errors for
                additional redundancy.
            </p>

            <p class="para">
                With the relevant information to hand, a subscription can be attempted as
                demonstrated below:
            </p>

            <pre class="programlisting brush: php">
$storage = new Zend_Feed_Pubsubhubbub_Model_Subscription;

$subscriber = new Zend_Feed_Pubsubhubbub_Subscriber;
$subscriber-&gt;setStorage($storage);
$subscriber-&gt;addHubUrl(&#039;http://hubbub.example.com&#039;);
$subscriber-&gt;setTopicUrl(&#039;http://www.example.net/rss.xml&#039;);
$subscriber-&gt;setCallbackUrl(&#039;http://www.mydomain.com/hubbub/callback&#039;);
$subscriber-&gt;subscribeAll();
</pre>


            <p class="para">
                In order to store subscriptions and offer access to this data for general use,
                the component requires a database (a schema is provided later in this section).
                By default, it is assumed the table name is &quot;subscription&quot; and it utilises
                <span class="classname">Zend_Db_Table_Abstract</span> in the background meaning it
                will use the default adapter you have set for your application. You may also
                pass a specific custom <span class="classname">Zend_Db_Table_Abstract</span> instance
                into the associated model
                <span class="classname">Zend_Feed_Pubsubhubbub_Model_Subscription</span>. This custom
                adapter may be as simple in intent as changing the table name to use or as complex
                as you deem necessary.
            </p>

            <p class="para">
                While this Model is offered as a default ready-to-roll solution, you may create your
                own Model using any other backend or database layer (e.g. Doctrine) so long as the
                resulting class implements the interface
                <span class="classname">Zend_Feed_Pubsubhubbub_Model_SubscriptionInterface</span>.
            </p>

            <p class="para">
                An example schema (MySQL) for a subscription table accessible by the provided model
                may look similar to:
            </p>

            <pre class="programlisting brush: sql">
CREATE TABLE IF NOT EXISTS `subscription` (
  `id` varchar(32) COLLATE utf8_unicode_ci NOT NULL DEFAULT &#039;&#039;,
  `topic_url` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
  `hub_url` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
  `created_time` datetime DEFAULT NULL,
  `lease_seconds` bigint(20) DEFAULT NULL,
  `verify_token` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
  `secret` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
  `expiration_time` datetime DEFAULT NULL,
  `subscription_state` varchar(12) COLLATE utf8_unicode_ci DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
</pre>


            <p class="para">
                Behind the scenes, the Subscriber above will send a request to the Hub endpoint
                containing the following parameters (based on the previous example):
            </p>

            <table id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.subscriber.subscribing.and.unsubscribing.table" class="doctable table"><div class="info"><caption><b>Subscription request parameters</b></caption></div>
                

                
                    <thead valign="middle">
                        <tr valign="middle">
                            <th>Parameter</th>
                            <th>Value</th>
                            <th>Explanation</th>
                        </tr>

                    </thead>


                    <tbody valign="middle" class="tbody">
                        <tr valign="middle">
                            <td align="left"><span class="property">hub.callback</span></td>
                            <td align="left">http://www.mydomain.com/hubbub/callback?xhub.subscription=5536df06b5dcb966edab3a4c4d56213c16a8184</td>

                            <td align="left">
                                <p class="para">
                                    The <acronym class="acronym">URI</acronym> used by a Hub to contact the
                                    Subscriber and either request confirmation of a (un)subscription
                                    request or send updates from subscribed feeds. The appended
                                    query string contains a custom parameter (hence the xhub
                                    designation). It is a query string parameter preserved by the
                                    Hub and resent with all Subscriber requests. Its purpose is to
                                    allow the Subscriber to identify and look up the subscription
                                    associated with any Hub request in a backend storage medium.
                                    This is a non-standard parameter used by this component in
                                    preference to encoding a subscription key in the
                                    <acronym class="acronym">URI</acronym> path which is more difficult to implement
                                    in a Zend Framework application.
                                </p>

                                <p class="para">
                                    Nevertheless, since not all Hubs support query string
                                    parameters, we still strongly recommend adding the subscription
                                    key as a path component in the form
                                    http://www.mydomain.com/hubbub/callback/5536df06b5dcb966edab3a4c4d56213c16a8184.
                                    To accomplish this, it requires defining a route capable of
                                    parsing out the final value of the key and then retrieving the
                                    value and passing it to the Subscriber Callback object. The
                                    value would be passed into the method
                                     <span class="methodname">Zend_Pubsubhubbub_Subscriber_Callback::setSubscriptionKey()</span>.
                                    A detailed example is offered later.
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.lease_seconds</span></td>
                            <td align="left">2592000</td>

                            <td align="left">
                                <p class="para">
                                    The number of seconds for which the Subscriber would like a new
                                    subscription to remain valid for (i.e. a
                                    <acronym class="acronym">TTL</acronym>). Hubs may enforce their own maximum
                                    subscription period. All subscriptions should be renewed by
                                    simply re-subscribing before the subscription period ends to
                                    ensure continuity of updates. Hubs should additionally attempt
                                    to automatically refresh subscriptions before they expire by
                                    contacting Subscribers (handled automatically by the Callback
                                    class).
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.mode</span></td>
                            <td align="left">subscribe</td>

                            <td align="left">
                                <p class="para">
                                    Simple value indicating this is a subscription request.
                                    Unsubscription requests would use the &quot;unsubscribe&quot; value.
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.topic</span></td>
                            <td align="left">http://www.example.net/rss.xml</td>

                            <td align="left">
                                <p class="para">
                                    The <acronym class="acronym">URI</acronym> of the topic (i.e. Atom or
                                    <acronym class="acronym">RSS</acronym> feed) which the Subscriber wishes to
                                    subscribe to for updates.
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.verify</span></td>
                            <td align="left">sync</td>

                            <td align="left">
                                <p class="para">
                                    Indicates to the Hub the preferred mode of verifying
                                    subscriptions or unsubscriptions. It is repeated twice in order
                                    of preference. Technically this component does not distinguish
                                    between the two modes and treats both equally.
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.verify</span></td>
                            <td align="left">async</td>

                            <td align="left">
                                <p class="para">
                                    Indicates to the Hub the preferred mode of verifying
                                    subscriptions or unsubscriptions. It is repeated twice in order
                                    of preference. Technically this component does not distinguish
                                    between the two modes and treats both equally.
                                </p>
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><span class="property">hub.verify_token</span></td>
                            <td align="left">3065919804abcaa7212ae89.879827871253878386</td>

                            <td align="left">
                                <p class="para">
                                    A verification token returned to the Subscriber by the Hub when
                                    it is confirming a subscription or unsubscription. Offers a
                                    measure of reliance that the confirmation request originates
                                    from the correct Hub to prevent misuse.
                                </p>
                            </td>
                        </tr>

                    </tbody>
                
            </table>


            <p class="para">
                You can modify several of these parameters to indicate a different preference. For
                example, you can set a different lease seconds value using
                 <span class="methodname">Zend_Pubsubhubbub_Subscriber::setLeaseSeconds()</span> or show a
                preference for the async verify mode by using
                 <span class="methodname">setPreferredVerificationMode(Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_ASYNC)</span>.
                However the Hubs retain the capability to enforce their own preferences and for this
                reason the component is deliberately designed to work across almost any set of
                options with minimum end-user configuration required. Conventions are great when
                they work!
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    While Hubs may require the use of a specific verification mode (both are
                    supported by <span class="classname">Zend_Pubsubhubbub</span>), you may indicate a
                    specific preference using the
                     <span class="methodname">setPreferredVerificationMode()</span> method. In &quot;sync&quot;
                    (synchronous) mode, the Hub attempts to confirm a subscription as soon as it is
                    received, and before responding to the subscription request. In &quot;async&quot;
                    (asynchronous) mode, the Hub will return a response to the subscription request
                    immediately, and its verification request may occur at a later time. Since
                    <span class="classname">Zend_Pubsubhubbub</span> implements the Subscriber verification
                    role as a separate callback class and requires the use of a backend storage
                    medium, it actually supports both transparently though in terms of end-user
                    performance, asynchronous verification is very much preferred to eliminate the
                    impact of a poorly performing Hub tying up end-user server resources and
                    connections for too long.
                </p>
            </p></blockquote>

            <p class="para">
                Unsubscribing from a Topic follows the exact same pattern as the previous example,
                with the exception that we should call  <span class="methodname">unsubscribeAll()</span>
                instead. The parameters included are identical to a subscription request with the
                exception that &quot;<span class="property">hub.mode</span>&quot; is set to &quot;unsubscribe&quot;.
            </p>

            <p class="para">
                By default, a new instance of <span class="classname">Zend_Pubsubhubbub_Subscriber</span>
                will attempt to use a database backed storage medium which defaults to using the
                default <span class="classname">Zend_Db</span> adapter with a table name of &quot;subscription&quot;.
                It is recommended to set a custom storage solution where these defaults are not apt
                either by passing in a new Model supporting the required interface or by passing a
                new instance of <span class="classname">Zend_Db_Table_Abstract</span> to the default Model&#039;s
                constructor to change the used table name.
            </p>
        </div>

        <div class="section" id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.subscriber.handling.hub.callbacks"><div class="info"><h1 class="title">Handling Subscriber Callbacks</h1></div>
            

            <p class="para">
                Whenever a subscription or unsubscription request is made, the Hub must verify the
                request by forwarding a new verification request to the Callback
                <acronym class="acronym">URL</acronym> set in the subscription or unsubscription parameters. To
                handle these Hub requests, which will include all future communications containing
                Topic (feed) updates, the Callback <acronym class="acronym">URL</acronym> should trigger the
                execution of an instance of
                <span class="classname">Zend_Pubsubhubbub_Subscriber_Callback</span> to handle the request.
            </p>

            <p class="para">
                The Callback class should be configured to use the same storage medium as the
                Subscriber class. Using it is quite simple since most of its work is performed
                internally.
            </p>

            <pre class="programlisting brush: php">
$storage = new Zend_Feed_Pubsubhubbub_Model_Subscription;
$callback = new Zend_Feed_Pubsubhubbub_Subscriber_Callback;
$callback-&gt;setStorage($storage);
$callback-&gt;handle();
$callback-&gt;sendResponse();

/**
 * Check if the callback resulting in the receipt of a feed update.
 * Otherwise it was either a (un)sub verification request or invalid request.
 * Typically we need do nothing other than add feed update handling - the rest
 * is handled internally by the class.
 */
if ($callback-&gt;hasFeedUpdate()) {
    $feedString = $callback-&gt;getFeedUpdate();
    /**
     *  Process the feed update asynchronously to avoid a Hub timeout.
     */
}
</pre>


            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    It should be noted that
                    <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> may
                    independently parse any incoming query string and other parameters. This is
                    necessary since <acronym class="acronym">PHP</acronym> alters the structure and keys of a query
                    string when it is parsed into the <var class="varname">$_GET</var> or
                    <var class="varname">$_POST</var> superglobals. For example, all duplicate keys are
                    ignored and periods are converted to underscores. Pubsubhubbub features both of
                    these in the query strings it generates.
                </p>
            </p></blockquote>

            <div class="important"><b class="important">Important</b>
                <p class="para">
                    It is essential that developers recognise that Hubs are only concerned with
                    sending requests and receiving a response which verifies its receipt. If a feed
                    update is received, it should never be processed on the spot since this leaves
                    the Hub waiting for a response. Rather, any processing should be offloaded to
                    another process or deferred until after a response has been returned to the Hub.
                    One symptom of a failure to promptly complete Hub requests is that a Hub may
                    continue to attempt delivery of the update or verification request leading to
                    duplicated update attempts being processed by the Subscriber. This appears
                    problematic - but in reality a Hub may apply a timeout of just a few seconds,
                    and if no response is received within that time it may disconnect (assuming a
                    delivery failure) and retry later. Note that Hubs are expected to distribute
                    vast volumes of updates so their resources are stretched - please do process
                    feeds asynchronously (e.g. in a separate process or a job queue or even a cron
                    scheduled task) as much as possible.
                </p>
            </div>
        </div>

        <div class="section" id="zend.feed.pubsubhubbub.zend.feed.pubsubhubbub.subscriber.setting.up.and.using.a.callback.url.route"><div class="info"><h1 class="title">Setting Up And Using A Callback URL Route</h1></div>
            

            <p class="para">
                As noted earlier, the
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> class receives the
                combined key associated with any subscription from the Hub via one of two methods.
                The technically preferred method is to add this key to the Callback
                <acronym class="acronym">URL</acronym> employed by the Hub in all future requests using a query
                string parameter with the key &quot;xhub.subscription&quot;. However, for historical reasons,
                primarily that this was not supported in Pubsubhubbub 0.1 (it was recently added in
                0.2 only), it is strongly recommended to use the most compatible means of adding
                this key to the Callback <acronym class="acronym">URL</acronym> by appending it to the
                <acronym class="acronym">URL</acronym>&#039;s path.
            </p>

            <p class="para">
                Thus the <acronym class="acronym">URL</acronym>
                http://www.example.com/callback?xhub.subscription=key would become
                http://www.example.com/callback/key.
            </p>

            <p class="para">
                Since the query string method is the default in anticipation of a greater level
                of future support for the full 0.2 specification, this requires some additional work
                to implement.
            </p>

            <p class="para">
                The first step to make the
                <span class="classname">Zend_Feed_Pubsubhubbub_Subscriber_Callback</span> class aware of the
                path contained subscription key. It&#039;s manually injected therefore since it also
                requires manually defining a route for this purpose. This is achieved simply by
                called the method
                 <span class="methodname">Zend_Feed_Pubsubhubbub_Subscriber_Callback::setSubscriptionKey()</span>
                with the parameter being the key value available from the Router. The example below
                demonstrates this using a Zend Framework controller.
            </p>

            <pre class="programlisting brush: php">
class CallbackController extends Zend_Controller_Action
{

    public function indexAction()
    {
        $storage = new Zend_Feed_Pubsubhubbub_Model_Subscription;
        $callback = new Zend_Feed_Pubsubhubbub_Subscriber_Callback;
        $callback-&gt;setStorage($storage);
        /**
         * Inject subscription key parsing from URL path using
         * a parameter from Router.
         */
        $subscriptionKey = $this-&gt;_getParam(&#039;subkey&#039;);
        $callback-&gt;setSubscriptionKey($subscriptionKey);
        $callback-&gt;handle();
        $callback-&gt;sendResponse();

        /**
         * Check if the callback resulting in the receipt of a feed update.
         * Otherwise it was either a (un)sub verification request or invalid
         * request. Typically we need do nothing other than add feed update
         * handling - the rest is handled internally by the class.
         */
        if ($callback-&gt;hasFeedUpdate()) {
            $feedString = $callback-&gt;getFeedUpdate();
            /**
             *  Process the feed update asynchronously to avoid a Hub timeout.
             */
        }
    }

}
</pre>


        <p class="para">
            Actually adding the route which would map the path-appended key
            to a parameter for retrieval from a controller can be accomplished using
            a Route configuration such as the <acronym class="acronym">INI</acronym> formatted example below for
            use with <span class="classname">Zend_Application</span> bootstrapping.
        </p>

        <pre class="programlisting brush: dosini">
; Callback Route to enable appending a PuSH Subscription&#039;s lookup key
resources.router.routes.callback.route = &quot;callback/:subkey&quot;
resources.router.routes.callback.defaults.module = &quot;default&quot;
resources.router.routes.callback.defaults.controller = &quot;callback&quot;
resources.router.routes.callback.defaults.action = &quot;index&quot;
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.feed.writer.html">Zend_Feed_Writer</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.feed.html">Zend_Feed</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.file.html">Zend_File</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.feed.html">Zend_Feed</a></li>
  <li><a href="zend.feed.introduction.html">Introduction</a></li>
  <li><a href="zend.feed.importing.html">Importing Feeds</a></li>
  <li><a href="zend.feed.findFeeds.html">Retrieving Feeds from Web Pages</a></li>
  <li><a href="zend.feed.consuming-rss.html">Consuming an RSS Feed</a></li>
  <li><a href="zend.feed.consuming-atom.html">Consuming an Atom Feed</a></li>
  <li><a href="zend.feed.consuming-atom-single-entry.html">Consuming a Single Atom Entry</a></li>
  <li><a href="zend.feed.modifying-feed.html">Modifying Feed and Entry structures</a></li>
  <li><a href="zend.feed.custom-feed.html">Custom Feed and Entry Classes</a></li>
  <li><a href="zend.feed.reader.html">Zend_Feed_Reader</a></li>
  <li><a href="zend.feed.writer.html">Zend_Feed_Writer</a></li>
  <li class="active"><a href="zend.feed.pubsubhubbub.introduction.html">Zend_Feed_Pubsubhubbub</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>